SDK详情
本文主要介绍如何使用SDK调用阿里云百炼的应用,即从应用中心->我的应用中新建的应用。
SDK详情
前提条件
已开通百炼服务: 开通阿里云百炼大模型服务产品。
已创建API-KEY:获取API-KEY。
已安装最新版SDK:安装SDK。
已创建应用:应用中心,并获取到APP_ID:获取APP-ID和WORKSPACE。
快速调用
以下示例展示了调用应用的代码。
需要使用您的API-KEY替换示例中的YOUR_API_KEY,并将APP-ID替换示例中的YOUR_APP_ID,代码才能正常运行。
python sdk version: dashscope>=1.10.0
java sdk version: >=2.5.0
设置API-KEY
export DASHSCOPE_API_KEY=YOUR_API_KEY
调用示例
from http import HTTPStatus
from dashscope import Application
def app_call():
response = Application.call(app_id='YOUR_APP_ID',
prompt='API接口说明中, TopP参数改如何传递?',
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))
if __name__ == '__main__':
app_call()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.List;
public class Main{
public static void appCall()
throws ApiException, NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("API接口说明中, TopP参数改如何传递?")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
if (result.getUsage() != null && result.getUsage().getModels() != null) {
for (ApplicationUsage.ModelUsage usage : result.getUsage().getModels()) {
System.out.printf("modelId: %s, inputTokens: %d, outputTokens: %d\n",
usage.getModelId(), usage.getInputTokens(), usage.getOutputTokens());
}
}
}
public static void main(String[] args) {
try {
appCall();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
throw new RuntimeException(e);
}
System.exit(0);
}
}
多轮会话
阿里云百炼应用提供云端托管多轮对话功能,通过session_id进行多轮会话,阿里云百炼云端将自动托管多轮会话,调用侧无需自行维护多轮会话。
下面的例子中,第一次调用后返回session_id,在第二次调用时,可以传入第一次返回的session_id,这样第二次调用模型服务时,将携带第一次调用的会话信息。
目前session id会话有效期是1个小时,最大历史会话轮数为50。
from http import HTTPStatus
from dashscope import Application
def call_with_session():
response = Application.call(app_id='YOUR_APP_ID',
prompt='我想去新疆',
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
return
response = Application.call(app_id='your app id',
prompt='那边有什么旅游景点或者美食?',
session_id=response.output.session_id
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s, output=%s, usage=%s\n' % (response.request_id, response.output, response.usage))
if __name__ == '__main__':
call_with_session()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void callWithSession()
throws ApiException, NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("我想去新疆")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
param.setSessionId(result.getOutput().getSessionId());
param.setPrompt("那边有什么旅游景点或者美食?");
result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
}
public static void main(String[] args) {
try {
callWithSession();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}
流式输出
流式输出需要添加对应参数。其中,Python SDK中需要添加stream=True,Java SDK中需要使用streamCall接口调用。
from http import HTTPStatus
from dashscope import Application
def call_with_stream():
responses = Application.call(app_id='YOUR_APP_ID',
prompt='如何做炒西红柿鸡蛋?',
stream=True
)
for response in responses:
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (
response.request_id, response.status_code, response.message))
else:
print('output=%s, usage=%s\n' % (response.output, response.usage))
if __name__ == '__main__':
call_with_stream()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import io.reactivex.Flowable;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void streamCall() throws NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("如何做土豆炖猪脚?")
.build();
Application application = new Application();
Flowable<ApplicationResult> result = application.streamCall(param);
result.blockingForEach(data -> {
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason());
});
}
public static void main(String[] args) {
try {
streamCall();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}
业务空间
上述调用示例调用的是默认业务空间的应用,如果需要调用其他业务空间,需要传入指定的业务空间标识。
请将WORKSPACE替换示例中的YOUR_WORKSPACE,代码才能正常运行。请参考获取APP-ID和WORKSPACE获取WORKSPACE。
from http import HTTPStatus
from dashscope import Application
def call_with_workspace():
response = Application.call(app_id='YOUR_APP_ID',
workspace='YOUR_WORKSPACE',
prompt='如何做炒西红柿鸡蛋?',
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s, text=%s, usage=%s\n' % (response.request_id, response.output.text, response.usage))
if __name__ == '__main__':
call_with_workspace()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
public class Main {
public static void callWithWorkspace() throws NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.workspace("YOUR_WORKSPACE")
.appId("YOUR_APP_ID")
.prompt("如何做土豆炖猪脚?")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
}
public static void main(String[] args) {
try {
callWithWorkspace();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}
输入参数
参数 | 类型 | 默认值 | 说明 |
app_id | string | - | 应用标识。 |
prompt | string | - | 用户当前输入的期望模型执行指令,用于指导模型生成回复。 |
session_id | string | - | 对话历史会话唯一标识,传入session_id后,将在云端进行对话历史记录,调用大模型将自动携带存储的对话历史。请确保session_id不重复,并且session_id和history二选一即可。 |
workspace(可选) | string | - | 业务空间标识,当调用子业务空间的应用时,需要传递workspace标识,调用默认业务空间的应用无需传递workspace。 |
stream (可选) | bool | False | 是否使用流式输出。当以stream模式输出结果时,接口返回结果为generator,需要通过迭代获取结果,默认每次输出为当前生成的整个序列,最后一次输出为最终全部生成结果。 |
has_thoughts | bool | False | 是否输出插件调用和知识检索过程信息。开启后,将返回插件调用和知识检索的过程信息。 |
输出参数
返回参数 | 类型 | 说明 | 备注 |
status_code | int | 200(HTTPStatus.OK)表示请求成功,否则表示请求失败,可以通过code获取错误码,通过message字段获取错误详细信息。 说明 Python才有这个字段,Java失败会抛出异常,异常信息为code,message内容。 | |
request_Id | string | 系统生成的标识本次调用的id。 | |
code | string | 表示请求失败,表示错误码,成功忽略。 python only | |
message | string | 失败,表示失败详细信息,成功忽略。 python only | |
output | dict | 调用结果信息,对于千问模型,包含输出text。 | |
output.text | string | 模型生成回复。 | |
output.finish_reason | string | 正在生成时为null,生成结束时如果由于停止token导致则为stop。 | |
output.session_id | string | 对话历史会话的唯一标识. | 在多轮会话时,可以使用此标识进行多轮会话保持。 |
output.thoughts[].throught | string | 模型的思考结果。 | |
output.thoughts[].action_type | string | 大模型返回的执行步骤类型 api: 执行api插件, response: 返回最终结果。 | |
output.thoughts[].action_name | string | 执行的action名称,如文档检索、API插件。 | |
output.thoughts[].action | string | 执行的步骤。 | |
output.thoughts[].action_input_stream | string | 入参的流式结果。 | |
output.thoughts[].action_input | string | 插件的输入参数。 | |
output.thoughts[].response | string | 模型调用返回的结果。 | |
output.thoughts[].observation | string | 检索或插件的返回结果。 | |
usage | dict | 计量信息,表示本次请求的计量数据。 | |
usage.models[].model_id | string | 本次应用调用到的模型。 | |
usage.models[].input_tokens | int | 用户输入文本转换成Token后的长度。 | |
usage.models[].output_tokens | int | 模型生成回复转换为Token后的长度。 |
- 本页导读 (1)